Bug: double # prefix produces malformed headings

trimmed already starts with #, so "##" + trimmed yields ## # Title — a level-2 heading whose display text is the literal string # Title. The same pattern exists in the production main.go parsing path, so the skeleton files and the rendered output will be consistent, but the heading levels will be wrong (H2 for content that was a bare # comment in the source).

If the intent is to promote .gop #-lines to Markdown H2s, strip the leading # first:

docText = "## " + strings.TrimPrefix(strings.TrimPrefix(trimmed, "#"), " ")

Or if the transformation in main.go should be the canonical one, keep both files in sync with the same logic.

Only the first character of the chapter prefix is validated as numeric

name[:1] is a single character. A directory named 1AB-Something would pass this check even though its prefix is not a valid three-digit number. Use name[:chNumLen] to validate the full prefix:

if _, e := strconv.Atoi(name[:chNumLen]); e == nil {

os.Stat error is not distinguished from "file not found"

If os.Stat fails for a reason other than the file not existing (e.g. a permissions issue), the code silently proceeds to write a new file. Prefer:

if _, err := os.Stat(mdPath); err == nil {
    skipped++
    continue
} else if !os.IsNotExist(err) {
    fmt.Fprintf(os.Stderr, "Warning: cannot stat %s: %v\n", mdPath, err)
    continue
}

--- without surrounding blank lines is parsed as a setext H2 heading

In CommonMark, a line of --- immediately following text is interpreted as a setext-style H2 heading for that text, not as a thematic break. This means the last line of each doc segment will be rendered as a heading rather than as a divider. Add blank lines around the separator:

skeleton := strings.Join(docs, "\n\n---\n\n")

os.MkdirAll called once per source file rather than once per directory

All .gop/.xgo files in the same dir share the same langDir. Moving this call outside the inner fi loop (or hoisting it just before the inner loop begins) avoids the redundant syscall for every file after the first in each directory.

Path traversal via unsanitized lang argument

lang is used directly in filepath.Join("locales", lang, ...) for both os.MkdirAll and os.WriteFile. While filepath.Join cleans the path, a value like ../../etc resolves outside locales/. Even for a //go:build ignore tool, validating the argument is a low-cost safeguard:

if !regexp.MustCompile(`^[a-z]{2,10}$`).MatchString(lang) {
    fmt.Fprintln(os.Stderr, "Error: lang must be a simple language code (e.g. zh, ja, ko)")
    os.Exit(1)
}

The same concern applies to directory values passed explicitly via os.Args[2:] — each entry should be checked to contain no path separators.

en.json is missing the titles object present in all other locale files

zh.json, ja.json, and ko.json all include a "titles" map of English tutorial names → localized names. en.json omits it entirely, making it structurally inconsistent with the other locale files. Since en.json is the canonical schema reference for contributors adding new locales, the missing key is likely to cause incomplete locale files in the future.

Consider adding identity mappings (English → English) or at minimum a comment/schema file in locales/ documenting the expected structure.

The logic strconv.Atoi(name[:1]) is fragile and potentially incorrect given that chNumLen is set to 3. If the directory naming convention uses a 3-digit prefix (e.g., 101-), it is safer to validate the entire prefix.

The text refers to "Go" instead of "XGo". To maintain consistency with the rest of the documentation and the project's branding, this should be updated.

The text refers to "Go" instead of "XGo". This should be updated for consistency.

The text refers to "Go" instead of "XGo". This should be updated for consistency.

The title translation for "Hello world" is missing the Japanese part, unlike other entries which follow the bilingual format (e.g., "Values 値").

The title translation for "Hello world" is missing the Korean part, unlike other entries which follow the bilingual format.

The title translation for "Hello world" is missing the Chinese part, unlike other entries which follow the bilingual format.